{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n",
    "SPDX-License-Identifier: Apache-2.0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# What are Neptune Notebooks?\n",
    "\n",
    "The workbench is an interactive environment that hosts [Jupyter notebooks](https://jupyter-notebook.readthedocs.io/en/stable/) along with a set of tools that make it easy to get started with Neptune. If you are already familiar with Neptune Notebooks, explore these popular sample graph applications:\n",
    "\n",
    "[Introduction to Fraud Graphs](../03-Sample-Applications/01-Fraud-Graphs/01-Building-a-Fraud-Graph-Application.ipynb)<br>\n",
    "[Introduction to Knowledge Graphs](../03-Sample-Applications/02-Knowledge-Graphs)<br>\n",
    "[Introduction to Identity Graphs](../03-Sample-Applications/03-Identity-Graphs/01-Building-an-Identity-Graph-Application.ipynb)<br>\n",
    "[Introduction to Security Graphs](../03-Sample-Applications/04-Security-Graphs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What is a Jupyter notebook?\n",
    "\n",
    "Jupyter is a web-based application that lets you author and interact with 'notebook' documents.  The [Jupyter](https://jupyter.org/) open-source project that develops it provides [documentation](https://jupyter-notebook.readthedocs.io/en/stable/) of its own.\n",
    "\n",
    "A notebook document consists of a series of 'cells'. A cell can contain one of:\n",
    "\n",
    "- Explanatory text authored in Markdown, or\n",
    "- Code that you can run (the programming language depends on the kernel that your server is using), or\n",
    "- The output that is produced when you run the code.\n",
    "\n",
    "The user interface of a notebook is fairly self-explanatory. You can create a new notebook from the `File` menu. Once you have a notebook open, you can edit a cell by double-clicking on its interior. If you are editing a Markdown cell, you can render its HTML by \"running\" it. You can run a selected cell using the `Run` button on the toolbar (if the toolbar is hidden, use the `View` menu to toggle it on). The `Edit` and `Cell` menus provide a large number of operations, and `Keyboard Shortcuts` on the `Help` menu displays a long list of commands with corresponding key shortcuts.\n",
    "\n",
    "Markdown text cells have a height limit, which forces you to break explanations into small, manageable blocks.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Neptune Notebook Workbench Features\n",
    "\n",
    "You can use notebooks in the workbench to load data into a database through the Neptune `loader` endpoint, check the database status using the `status` endpoint, and try out Gremlin or SPARQL to make queries against your database.\n",
    "\n",
    "By default, the workbench uses the IPython 3 kernel. It also provides a number of useful extensions:\n",
    "\n",
    "#### Notebook cell 'magic' extensions in the IPython 3 kernel\n",
    "\n",
    "- `%%sparql` - Executes a SPARQL query against your configured database endpoint.\n",
    "\n",
    "- `%%gremlin` - Executes a Gremlin query against your database using web sockets. The results are similar to what the Gremlin console would return.\n",
    "\n",
    "- `%%opencypher`/`%%oc` - Executes an openCypher query against your database. By default, the HTTPS endpoint is used. The `bolt` mode can be specified to instead run openCypher queries via the Bolt protocol.\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Notebook line 'magic' extensions for the IPython 3 kernel\n",
    "- `%status` - Calls the Neptune [status endpoint](https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-status.html), which returns information about the health and configuration of your DB cluster, as a JSON object.\n",
    "\n",
    "- `%load` - Invokes the [Neptune bulk loader](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load.html).\n",
    "\n",
    "- `%graph_notebook_config` - Returns a JSON object that contains connection information for your host.\n",
    "\n",
    "- `%seed` - Provides a form to add data to your graph without the use of a bulk loader. Several PropertyGraph and RDF datasets are already included with graph-notebook. Alternatively, you can load from files on your local disk by providing the language of the datatype and the full path to a file, or a directory containing at least one of these files.\n",
    "\n",
    "#### 'Nbextensions' that add to the notebook user interface\n",
    "- The `Neptune` menu item at the top displays connection information for the host you are connected to (this is the same information that `%graph_notebook_config` returns).\n",
    "- There is syntax highlighting for `%%sparql`, `%%gremlin`, and `%%opencypher` queries to help you write good code.\n",
    "\n",
    "You can list all the magics installed in the Python 3 kernel using the `%lsmagic` command.\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Try out checking the status of your cluster\n",
    "\n",
    "The `%status` magic can be used to check for the health of your cluster, as well as  retrieve additional information such as the engine version.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%status"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Try issuing some SPARQL queries\n",
    "\n",
    "You can issue a SPARQL query by using the `%%sparql` cell magic. Let's add a few items to the graph and then retrieve them:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%sparql\n",
    "\n",
    "INSERT DATA {\n",
    "    <http://s-1000-1> <http://p-1> <http://o-1> .\n",
    "    <http://s-1000-2> <http://p-2> <http://o-2> .\n",
    "    <http://s-1000-3> <http://p-3> <http://o-3> .\n",
    "    <http://s-1000-4> <http://p-4> <http://o-4> .\n",
    "    <http://s-1000-5> <http://p-5> <http://o-5> .\n",
    "    <http://s-1000-6> <http://p-6> <http://o-6> .\n",
    "    <http://s-1000-7> <http://p-7> <http://o-7> .\n",
    "    <http://s-1000-8> <http://p-8> <http://o-8> .\n",
    "    <http://s-1000-9> <http://p-9> <http://o-9> .\n",
    "    <http://s-1000-10> <http://p-10> <http://o-10> .\n",
    "    <http://s-1000-11> <http://p-11> <http://o-11> .\n",
    "    <http://s-1000-12> <http://p-12> <http://o-12> .\n",
    "    <http://s-1000-13> <http://p-13> <http://o-13> .\n",
    "    <http://s-1000-14> <http://p-14> <http://o-14> .\n",
    "    <http://s-1000-15> <http://p-15> <http://o-15> .\n",
    "    <http://s-1000-16> <http://p-16> <http://o-16> .\n",
    "    <http://s-1000-17> <http://p-17> <http://o-17> .\n",
    "    <http://s-1000-18> <http://p-18> <http://o-18> .\n",
    "    <http://s-1000-19> <http://p-19> <http://o-19> .\n",
    "    <http://s-1000-20> <http://p-20> <http://o-20> .\n",
    "}\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%sparql\n",
    "\n",
    "SELECT * WHERE {\n",
    "    ?s ?p ?o\n",
    "} LIMIT 10"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can look at the explain for this query by specifying it in the `%%sparql` cell magic's line component like below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%sparql explain\n",
    "\n",
    "SELECT * WHERE {\n",
    "    ?s ?p ?o\n",
    "} LIMIT 10"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Issuing Gremlin Queries\n",
    "\n",
    "You can issue a Gremlin query using the `%%gremlin` cell magic. Let's add a few vertices and then retrieve them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%gremlin\n",
    "\n",
    "g.addV('person').property('name', 'dan')\n",
    " .addV('person').property('name', 'mike')\n",
    " .addV('person').property('name', 'saikiran')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%gremlin\n",
    "\n",
    "g.V().limit(10)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%gremlin\n",
    "\n",
    "g.V().valueMap().limit(10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Like with `%%sparql`, there is an explain mode which can be toggled in the query."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%gremlin explain\n",
    "\n",
    "g.V().limit(10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Additionally, there is a profile mode in Gremlin which can be executed similarly to explain."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%gremlin profile\n",
    "\n",
    "g.V().limit(10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Issuing openCypher Queries\n",
    "\n",
    "You can issue an openCypher query using the `%%opencypher` (or just `%%oc`) cell magic. Let's populate the graph with a few elements, and then retrieve them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "%%oc\n",
    "\n",
    "CREATE (a:Language {name:\"Gremlin\"})\n",
    "CREATE (b:Language {name:\"Cypher\"})\n",
    "CREATE (c:Language {name:\"SPARQL\"})"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "%%oc\n",
    "\n",
    "MATCH (n)\n",
    "RETURN n\n",
    "LIMIT 10"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "Similar to the other query language magics, `%%oc` supports retrieval of a query explain plan."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    },
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "%%oc explain\n",
    "\n",
    "MATCH (n)\n",
    "RETURN n\n",
    "LIMIT 10"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What's next?\n",
    "\n",
    "Congratulations! You've completed the basic tutorial for the graph notebook. To learn more, here are some recommended notebooks:\n",
    "\n",
    "[More Gremlin Queries](./02-Using-Gremlin-to-Access-the-Graph.ipynb)\n",
    "\n",
    "[More SPARQL Queries](./03-Using-RDF-and-SPARQL-to-Access-the-Graph.ipynb)\n",
    "\n",
    "[Explore English Premier League using Gremlin](../02-Visualization/EPL-Gremlin.ipynb)\n",
    "\n",
    "[Explore English Premier League using SPARQL](../02-Visualization/EPL-SPARQL.ipynb)\n",
    "\n",
    "[Explore English Premier League using openCypher](../02-Visualization/EPL-openCypher.ipynb)\n",
    "\n",
    "Curious about the business problems can be solved with graph? Check out these sample application notebooks for some inspiration.\n",
    "\n",
    "[Introduction to Fraud Graphs](../03-Sample-Applications/01-Fraud-Graphs/01-Building-a-Fraud-Graph-Application.ipynb)\n",
    "\n",
    "[Introduction to Knowledge Graphs](../03-Sample-Applications/02-Knowledge-Graphs)\n",
    "\n",
    "[Introduction to Identity Graphs](../03-Sample-Applications/03-Identity-Graphs/01-Building-an-Identity-Graph-Application.ipynb)\n",
    "\n",
    "[Introduction to Security Graphs](../03-Sample-Applications/04-Security-Graphs)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
